home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1999 #1 / Amiga Plus 1999 #1.iso / System-Boost / Sound / Eagleplayer2.00 / Developer / Include / misc / DeliPlayer.i next >
Text File  |  1998-07-30  |  14KB  |  398 lines
  1. **
  2. **  $Filename: misc/DeliPlayer.i $
  3. **  $Release: 2.0 $
  4. **  $Revision: 2.15$
  5. **  $Date: 02/06/95$
  6. **
  7. **    Definitions and Macros for creating DeliTracker Player&Genie-modules
  8. **
  9. **    (C) Copyright 1991, 1992, 1993, 1994, 1995 Delirium Softdesign
  10. **        All Rights Reserved
  11. **
  12.  
  13.     IFND    DELITRACKER_PLAYER_I
  14. DELITRACKER_PLAYER_I    SET    1
  15.  
  16.     IFND EXEC_PORTS_I
  17.         INCLUDE "exec/ports.i"
  18.     ENDC
  19.  
  20.     IFND EXEC_TYPES_I
  21.         INCLUDE "exec/types.i"
  22.     ENDC
  23.  
  24.     IFND UTILITY_TAGITEM_I
  25.         INCLUDE "utility/tagitem.i"
  26.     ENDC
  27.  
  28. ;----------------------------------------------------------------------------
  29.  
  30. DELIVERSION    EQU    17            ; Current Version of DeliTracker
  31. DELIREVISION    EQU    4            ; Current Revision of DeliTracker
  32.  
  33.  
  34. ;------------------------ Player Function Offsets ---------------------------
  35.  
  36.  STRUCTURE DeliTrackerPlayer,0
  37.  
  38.     STRUCT    dtp_RTS_code,4            ; RTS for security (private !)
  39.     STRUCT    dtp_ID,8            ; Identifier (private !)
  40.     APTR    dtp_TagArray            ; pointer to TagItem array
  41.     LABEL    dtp_SIZE
  42.  
  43. * The TagItem ID's (ti_Tag values) for the player interface follow.
  44.  
  45. DTP_TagBase    EQU    TAG_USER+"DT"
  46.  
  47.     ENUM    DTP_TagBase            ; TagBase
  48.  
  49.     EITEM    DTP_InternalPlayer        ; obsolete
  50.     EITEM    DTP_CustomPlayer        ; player is a customplayer
  51.  
  52.     EITEM    DTP_RequestDTVersion        ; minimum DeliTracker version needed
  53.     EITEM    DTP_RequestKickVersion        ; minimum KickStart version needed
  54. DTP_RequestV37    EQU    DTP_RequestKickVersion    ; obsolete
  55.  
  56.     EITEM    DTP_PlayerVersion        ; actual player version & revision
  57.     EITEM    DTP_PlayerName            ; name of this player
  58.     EITEM    DTP_Creator            ; misc string
  59.  
  60.     EITEM    DTP_Check1            ; Check Format before loading
  61.     EITEM    DTP_Check2            ; Check Format after file is loaded
  62.     EITEM    DTP_ExtLoad            ; Load additional files
  63.     EITEM    DTP_Interrupt            ; Interrupt routine
  64.     EITEM    DTP_Stop            ; Clear Patterncounter
  65.     EITEM    DTP_Config            ; Config Player
  66.     EITEM    DTP_UserConfig            ; User-Configroutine
  67.     EITEM    DTP_SubSongRange        ; Get min&max subsong number
  68.  
  69.     EITEM    DTP_InitPlayer            ; Initialisize the Player
  70.     EITEM    DTP_EndPlayer            ; Player clean up
  71.     EITEM    DTP_InitSound            ; Soundinitialisation routine
  72.     EITEM    DTP_EndSound            ; End sound
  73.     EITEM    DTP_StartInt            ; Start interrupt
  74.     EITEM    DTP_StopInt            ; Stop interrupt
  75.  
  76.     EITEM    DTP_Volume            ; Set Volume
  77.     EITEM    DTP_Balance            ; Set Balance
  78.     EITEM    DTP_Faster            ; Incease playspeed
  79.     EITEM    DTP_Slower            ; Decrease playspeed
  80.     EITEM    DTP_NextPatt            ; Jump to next pattern
  81.     EITEM    DTP_PrevPatt            ; Jump to previous pattern
  82.     EITEM    DTP_NextSong            ; Play next subsong
  83.     EITEM    DTP_PrevSong            ; Play previous subsong
  84.  
  85.     ;--- functions in revision 14 (distributed as Release 1.35) ---
  86.  
  87.     EITEM    DTP_SubSongTest            ; Test, if given subsong is vaild
  88.  
  89.     ;--- functions in revision 16 (distributed as Release 2.01) ---
  90.  
  91.     EITEM    DTP_NewSubSongRange        ; enhanced replacement for DTP_SubSongRange
  92.  
  93.     EITEM    DTP_DeliBase            ; the address of a pointer where DT
  94.                         ; stores a pointer to the DeliGlobals
  95.  
  96.     EITEM    DTP_Flags            ; misc Flags (see below)
  97.  
  98.     EITEM    DTP_CheckLen            ; Length of the Check Code
  99.  
  100.     EITEM    DTP_Description            ; misc string
  101.  
  102.     EITEM    DTP_Decrunch            ; pointer to Decrunch Code
  103.     EITEM    DTP_Convert            ; pointer to Converter Code
  104.  
  105.     EITEM    DTP_NotePlayer            ; pointer to a NotePlayer Structure
  106.     EITEM    DTP_NoteStruct            ; the address of a pointer to the
  107.                         ; NoteStruct Structure
  108.     EITEM    DTP_NoteInfo            ; a pointer where DT stores a pointer
  109.                         ; to the current NoteStruct Structure
  110.     EITEM    DTP_NoteSignal            ; pointer to NoteSignal code
  111.  
  112.     EITEM    DTP_Process            ; pointer to process entry code
  113.     EITEM    DTP_Priority            ; priority of the process
  114.     EITEM    DTP_StackSize            ; stack size of the process
  115.     EITEM    DTP_MsgPort            ; a pointer where DT stores a pointer
  116.                         ; to a port to send its messages
  117.  
  118.     EITEM    DTP_Appear            ; open your window, if you can
  119.     EITEM    DTP_Disappear            ; go dormant
  120.  
  121.     EITEM    DTP_ModuleName            ; get the name of the current module
  122.     EITEM    DTP_FormatName            ; get the name of the module format
  123.     EITEM    DTP_AuthorName            ; not implemented yet
  124.  
  125.     ;--- functions in revision 17 (distributed as Release 2.07) ---
  126.  
  127.     EITEM    DTP_InitNote            ; NoteStruct initialization
  128.  
  129.     EITEM    DTP_NoteAllocMem    * allocates memory for module
  130.     EITEM    DTP_NoteFreeMem        * frees module-memory
  131.     EITEM    DTP_PlayerInfo        * a pointer where DT stores a pointer
  132.                     * to the current Player Taglist
  133.     EITEM    DTP_Patterns        * FPTR to a pattern-count routine
  134.     EITEM    DTP_Duration        * FPTR to a duration calc routine
  135.     EITEM    DTP_SampleData        * FPTR to a sample-info routine
  136.     EITEM    DTP_MiscText        * FPTR to a misc-text routine
  137.  
  138. *** end of player interface enumeration ***
  139.  
  140.  
  141. ; --- various flags ---------------------------------------------------------
  142.  
  143.     BITDEF    PLY,CUSTOM,0            ; the player is a customplayer
  144.     BITDEF    PLY,SONGEND,1            ; this player supports songend
  145.  
  146.     ;--- flags defined in revision 17 (distributed as Release 2.07) ---
  147.  
  148.     BITDEF    PLY,ANYMEM,2            ; modules of this player don't require chipmem
  149.  
  150.  
  151. ; --- DeliTracker message ---------------------------------------------------
  152.  
  153.    STRUCTURE DeliMessage,MN_SIZE
  154.     ULONG    DTMN_Function            ; function pointer
  155.     ULONG    DTMN_Result            ; store the result here
  156.    LABEL DTMN_SIZE
  157.  
  158.  
  159. ;------------------------------ Player Header -------------------------------
  160. ;
  161. ; Here is the MACRO for creating the player header structure. Use this MACRO !!!
  162.  
  163. PLAYERHEADER    MACRO
  164.     IFC    '\2',''
  165.     moveq    #-1,d0            ; this should return an error
  166.     rts                ; in case someone tried to run it
  167.     ELSE
  168.     bra.w    \2            ; branch to startupcode
  169.     ENDC
  170.     dc.b    'DELIRIUM'        ; identifier
  171.     dc.l    \1            ; ^tagitem array
  172.     ENDM
  173.  
  174.  
  175.     ;------ When a subroutine in the player is called, A5 will contain
  176.     ;------ the pointer to the DeliTrackerGlobals, the only exeption is
  177.     ;------ of course the interrupt routine.
  178.     ;------ The interruptroutine is called every 1/50 sec (via timerint).
  179.  
  180.     ;------ When Check is called, supply d0=0 if the format is ok
  181.     ;------ else d0<>0.
  182.  
  183.     ;------ Check1 is called before loading the complete file, you can
  184.     ;------ check in the first 1024 Bytes of the file. If the file is
  185.     ;------ smaller than 1kB, the remaining space will contain zero.
  186.  
  187.     ;------ Check2 is called after the complete file is loaded, you
  188.     ;------ can use dtg_ChkSize to determine the length of the file.
  189.     ;------ If you supply this tag the file can be crunched.
  190.  
  191.     ;------ ExtLoad: routine for loading additional files (instruments).
  192.     ;------    If successful, you must return d0=0 else d0<>0. In case of
  193.     ;------ an error DeliTracker frees all memory used for this module.
  194.  
  195.     ;------    InitPlayer: Here you should allocate the audio channels.
  196.     ;------ In case the player supports multi-modules, you must set here
  197.     ;------ dtg_SndNum to the minimal subsong number (not necessary if
  198.     ;------ you have supplied a DTP_SubSongRange routine!).
  199.     ;------ If successful, you must return d0=0 else d0<>0.
  200.  
  201.     ;------    EndPlayer: Here you should free the audio channels.
  202.  
  203.     ;------ InitSound: If you want to use the internal interrupt but don't
  204.     ;------ need the default 50 Hz frequency, you can write another timer
  205.     ;------ value into dtg_Timer.
  206.  
  207.     ;------ It is recommended to use DTP_SubSongRange/DTP_SubSongTest
  208.     ;------ instead of DTP_NextSong/DTP_PrevSong.
  209.  
  210.     ;------ Volume usually only copies the values dtg_Volume, dtg_SndLBal
  211.     ;------ and dtg_SndRBal to an internal buffer. The interrupt code has
  212.     ;------ access to this buffer and can set the volume correct.
  213.  
  214.     ;------ CheckLen: This tag is only allowed for players. If you supply
  215.     ;------ this tag, the player will be unloaded by DeliTracker in low
  216.     ;------ memory situations. When needed, it will be loaded again
  217.     ;------ automatically.
  218.  
  219.     ;------ Decrunch: Supply d0=0 if you could decrunch the file else
  220.     ;------ d0<>0.
  221.  
  222.     ;------ Convert: Supply d0=0 if you converted the file to another
  223.     ;------ format, else d0<>0.
  224.  
  225.     ;------ Appear: Supply d0<>0 if the window was already opend, else
  226.     ;------ d0=0.
  227.  
  228.     ;------ Disappear: Supply d0=0 if the window was already closed, else
  229.     ;------ d0<>0.
  230.  
  231.     ;------ ModuleName: This tag is only allowed for players. It contains
  232.     ;------ the address of a pointer to the module name (must be null
  233.     ;------ terminated). The tag is evaluated after the InitPlayer function
  234.     ;------ was called.
  235.  
  236.     ;------ FormatName: This tag is only allowed for convert genies. It
  237.     ;------ contains the address of a pointer to the name of the module
  238.     ;------ format (must be null terminated). The tag is evaluated after
  239.     ;------ the InitPlayer function was called.
  240.  
  241.     ;------ AuthorName: This tag is only allowed for players. It contains
  242.     ;------ the address of a pointer to the authorname (must be null
  243.     ;------ terminated). The tag is evaluated after the InitPlayer function
  244.     ;------ was called.
  245.  
  246.     ;------ Note: the Player can consist of more Hunks. That means you
  247.     ;------ can seperate CHIP DATA form CODE (and you should do this!).
  248.  
  249.  
  250. ;---------------------------- Global Variables ------------------------------
  251.  
  252.  STRUCTURE DeliTrackerGlobals,0
  253.  
  254.     ;------ if you use dtg_AslBase, make sure that
  255.     ;------ DTP_RequestDTVersion is at least 13 !
  256.  
  257.     APTR    dtg_AslBase        ; librarybase don't CloseLibrary()
  258.  
  259.     APTR    dtg_DOSBase        ; librarybase -"-
  260.     APTR    dtg_IntuitionBase    ; librarybase -"-
  261.     APTR    dtg_GfxBase        ; librarybase -"-
  262.     APTR    dtg_GadToolsBase    ; librarybase -"- (NULL for Kick 1.3 and below)
  263.     APTR    dtg_ReservedLibraryBase    ; reserved for future use
  264.  
  265.     APTR    dtg_DirArrayPtr        ; Ptr to the directory of the current module
  266.     APTR    dtg_FileArrayPtr    ; Ptr to the filename of the current module
  267.     APTR    dtg_PathArrayPtr    ; Ptr to PathArray (e.g used in LoadFile())
  268.  
  269.     APTR    dtg_ChkData        ; pointer to the module to be checked
  270.     ULONG    dtg_ChkSize        ; size of the module
  271.  
  272.     UWORD    dtg_SndNum        ; current sound number
  273.     UWORD    dtg_SndVol        ; volume (ranging from 0 to 64)
  274.     UWORD    dtg_SndLBal        ; left volume (ranging from 0 to 64)
  275.     UWORD    dtg_SndRBal        ; right volume (ranging from 0 to 64)
  276.     UWORD    dtg_LED            ; filter (0 if the LED is off)
  277.     UWORD    dtg_Timer        ; timer-value for the CIA-Timers
  278.  
  279.     FPTR    dtg_GetListData        ;
  280.     FPTR    dtg_LoadFile        ;
  281.     FPTR    dtg_CopyDir        ;
  282.     FPTR    dtg_CopyFile        ;
  283.     FPTR    dtg_CopyString        ;
  284.     FPTR    dtg_AudioAlloc        ;
  285.     FPTR    dtg_AudioFree        ;
  286.     FPTR    dtg_StartInt        ;
  287.     FPTR    dtg_StopInt        ;
  288.     FPTR    dtg_SongEnd        ; save to call from interrupt code !
  289.     FPTR    dtg_CutSuffix        ;
  290.  
  291.     ;------ extension in revision 14
  292.  
  293.     FPTR    dtg_SetTimer        ; save to call from interrupt code !
  294.  
  295.     ;------ extension in revision 15
  296.  
  297.     FPTR    dtg_WaitAudioDMA    ; save to call from interrupt code !
  298.  
  299.     ;------ extension in revision 16
  300.  
  301.     FPTR    dtg_LockScreen
  302.     FPTR    dtg_UnlockScreen
  303.     FPTR    dtg_NotePlayer        ; save to call from interrupt code !
  304.     FPTR    dtg_AllocListData
  305.     FPTR    dtg_FreeListData
  306.  
  307.     FPTR    dtg_Reserved1        ; do not use !!!
  308.     FPTR    dtg_Reserved2        ; do not use !!!
  309.     FPTR    dtg_Reserved3        ; do not use !!!
  310.  
  311.     ; There is no dtg_SIZEOF cause ...
  312.  
  313.  
  314.     ;------ GetListData(Num:d0): This function returns the memorylocation
  315.     ;------ of a loaded file in a0 and its size in d0. Num starts with 0
  316.     ;------ (the selected module). Example: GetListData(2) returns the
  317.     ;------ start of the third file loaded (via ExtLoad) in a0 an its size
  318.     ;------ in d0.
  319.  
  320.     ;------ LoadFile(): this function may only be called in the ExtLoad
  321.     ;------ routine. file/pathname must be in dtg_PathArrayPtr then
  322.     ;------ this function will attempt to load the file into CHIPMEM
  323.     ;------ (and DECRUNCH it). If everything went fine, d0 will be zero.
  324.     ;------ If d0 is not zero this indicates an error (e.g. read error,
  325.     ;------ not enough memory, ...).
  326.  
  327.     ;------ CopyDir(): this function copies the pathname at the end
  328.     ;------ of the string in dtg_PathArrayPtr(a5).
  329.  
  330.     ;------ CopyFile(): this function copies the filename at the end
  331.     ;------ of the string in dtg_PathArrayPtr(a5).
  332.  
  333.     ;------ CopyString(Ptr:a0): this function copies the string in a0
  334.     ;------ at the end of the string in dtg_PathArrayPtr(a5).
  335.  
  336.     ;------ AudioAlloc(): this function allocates the audiochannels
  337.     ;------ (only necessary if the player doesn't supply a NoteStruct
  338.     ;------ tag). If d0=0 all is ok, d0<>0 indicates an error.
  339.  
  340.     ;------ AudioFree(): this function frees the audiochannels allocated
  341.     ;------ with AudioAlloc().
  342.  
  343.     ;------ StartInt(): this function starts the timer-interrupt.
  344.  
  345.     ;------ StopInt(): this function stops the timer-interrupt started
  346.     ;------ with StartInt().
  347.  
  348.     ;------ SongEnd(): signal the songend to DeliTracker.
  349.     ;------ This call is guaranteed to preserve all registers.
  350.  
  351.     ;------ CutSuffix(): this function removes the suffix '.xpk' or '.pp'
  352.     ;------ from the string in dtg_PathArrayPtr(a5).
  353.  
  354.     ;------ SetTimer(): programs the CIA-Timer with the value supplied
  355.     ;------ in dtg_Timer(a5). Only useful, if the internal timer-interrupt
  356.     ;------ is used. This call is guaranteed to preserve all registers.
  357.  
  358.     ;------ WaitAudioDMA(): DMA delay wait. Only allowed, if the internal
  359.     ;------ timer-interrupt is used. This call is guaranteed to preserve
  360.     ;------ all registers.
  361.  
  362.     ;------ LockScreen(): this function tries to lock DeliTracker's screen.
  363.     ;------ It returns the screenpointer in d0 or NULL on failure.
  364.  
  365.     ;------ UnlockScreen(): this function unlocks DeliTracker's screen.
  366.     ;------ do not unlock a screen more times than it was locked!
  367.  
  368.     ;------ NotePlayer(): this call plays the notes specified in the
  369.     ;------ current NoteStruct structure. This function call is not allowed
  370.     ;------ if the active player doesn't have a valid NotePlayer structure.
  371.     ;------ do not call this function in interrupt code at interrupt
  372.     ;------ level 5 or higher! This call is guaranteed to preserve
  373.     ;------ all registers.
  374.  
  375.     ;------ AllocListData(Size:d0/Flags:d1): This is the memory allocator
  376.     ;------ for module specific memory to be used by all players and genies.
  377.     ;------ It provides a means of specifying that the allocation should be
  378.     ;------ made in a memory area accessible to the chips, or accessible to
  379.     ;------ shared system memory. If the allocation is successful,
  380.     ;------ DeliTracker will keep track of the new block (GetListData() will
  381.     ;------ return the location and size of this block).
  382.     ;------ byteSize - the size of the desired block in bytes.
  383.     ;------ Flags - the flags are passed through to AllocMem().
  384.     ;------ A pointer to the newly allocated memory block is returned in d0.
  385.     ;------ If there are no free memory regions large enough to satisfy the
  386.     ;------ request, zero will be returned. The pointer must be checked
  387.     ;------ for zero before the memory block may be used!
  388.  
  389.     ;------ FreeListData(MemBlock:a1): Free a region of memory allocated
  390.     ;------ with AllocListData(), returning it to the system pool from which
  391.     ;------ it came.
  392.     ;------ memoryBlock - pointer to the memory block to free, or NULL.
  393.  
  394.  
  395.     ENDC    ; DELITRACKER_PLAYER_I
  396.  
  397.  
  398.